---
type: engineering-note
title: Diagnosing with the Knowledge Base
description: A disciplined diagnosis loop that starts from the documented system instead of from grep.
tags: [engineering, skill]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Diagnosing with the Knowledge Base

_Adapted for this knowledge base from
[Matt Pocock's engineering skills](https://github.com/mattpocock/skills/tree/main/skills/engineering)
(diagnosing-bugs)._

## When to use
Hard bugs, regressions, "it worked yesterday".

## The loop
1. **Locate the flow.** Find the flow whose scenarios should cover the
   behaviour. Read the trunk's shared steps and the branch docs *before*
   reading code — the docs say what is supposed to happen.
2. **Classify the bug.**
   - Covered scenario failing → the cited `test://` evidence is your repro
     starting point; follow the row's `repo://`/`api://` URIs to the code.
   - **No scenario matches → the bug is first a documentation gap.** Add the
     missing scenario row (usually `unhappy` or `edge`) before fixing —
     that row is your repro spec, and it prevents the class, not just the
     instance.
3. **Check the data contract.** If state looks wrong, read the table's
   `## Columns` and the enum's `## Values` — half of "impossible states" are
   undeclared ones.
4. **Record the doubt.** A hypothesis you can't confirm is an open question
   with `About` on the suspect row — visible to the next person instead of
   dying in a thread.
5. **Fix = the TDD loop** from
   [TDD with Scenario Evidence](</Engineering/Skills/TDD with Scenario Evidence.md>):
   failing test from the new row, green, cite.

## Open questions